Measuring the performance of Kanzi Engine

Use the Profiling build to measure the performance of different parts of Kanzi Engine. This build includes profiled Kanzi libraries.

Performance profiling categories in the Profiling build

The Profiling build comes with performance profiling categories and profilers that you can use to measure the performance of different parts of Kanzi Engine:

Startup performance profiling categories

The startup performance profilers measure the time Kanzi Engine spends on different tasks during application startup. The startup performance profilers are registered in StartupProfilerRegistry. By default, all startup performance profiling categories are enabled. To set the state of a category in the application configuration, use the Configuration name. See ProfilingCategoryFilter.

This table lists the Kanzi startup performance profiling categories and profilers that are included in the Profiling build.

CategoryConfiguration nameProfiler
Application initializationStartupInitializationm_initializationProfiler
Default resource registrationStartupRegisterDefaultResourcesm_registerDefaultResourcesProfiler
Graphics initializationStartupInitializeGraphicsm_initializeGraphicsProfiler
GL subsystem initializationStartupInitializeGLm_initializeGLProfiler
Startup kzb file openingStartupOpenKzbm_openKzbProfiler
Loading threads initialization StartupInitializeLoadingThreadsm_initializeLoadingThreadsProfiler
Metadata registrationStartupRegisterMetadatam_registerMetadataProfiler
Plugins loadingStartupLoadPluginsm_loadPluginsProfiler
Prefabs loadingStartupLoadPrefabm_loadPrefabProfiler
Prefabs instantiationStartupInstantiatePrefabm_instantiatePrefabProfiler
Prefabs attachmentStartupAttachPrefabm_attachPrefabProfiler
Renderer resetStartupResetRendererm_resetRendererProfiler
Runtime assets registrationStartupRegisterRuntimeAssetsm_registerRuntimeAssetsProfiler
   

Main loop task performance profiling categories

The main loop task performance profilers measure the time Kanzi Engine spends on different tasks on each iteration of the Kanzi main loop. The main loop task performance profilers are registered in the MainLoopTaskProfilerRegistry. By default, all main loop task performance profiling categories are enabled. To set the state of a category in the application configuration, use the Configuration name. See ProfilingCategoryFilter.

This table lists the Kanzi main loop task performance profiling categories and profilers that are included in the Profiling build.

CategoryConfiguration nameTitle in HUDProfiler
Animations
Measures the time spent rendering animations.
MainLoopAnimationMain loop: animationm_animationProfiler
Application events handling
Measures the time spent gathering and handling events from all available event sources, such as keyboard, mouse, and other available manipulators.
MainLoopApplicationEventsMain loop: application eventsm_applicationEventsProfiler
Application logic updating
Measures the time spent inside the Application::update override that you provide.
MainLoopAppUpdateMain loop: application updatem_appUpdateProfiler
User-provided application logic updating
Measures the time spent executing the update logic callback Application::onUpdate that you provide.
MainLoopUserUpdateMain loop: user updatem_userUpdateProfiler
Graphics events handling
Measures the time spent processing events that affect graphics output, such as resizing a window.
MainLoopGraphicsEventsMain loop: graphics eventsm_graphicsEventsProfiler
Performance HUD
Measures the overhead caused by rendering the information in the Performance HUD.
MainLoopHUDMain loop: HUDm_hudProfiler
Input events handling
Measures the time that the InputManager spends processing input events, such as keyboard and mouse events.
MainLoopInputMain loop: inputm_inputProfiler
Layout
Measures the performance of the layout pass.
MainLoopLayoutMain loop: layoutm_layoutProfiler
Rendering
Measures the time spent rendering the screen in Application::renderOverride.
MainLoopRenderingMain loop: renderingm_renderingProfiler
Resource deployment
Measures the time spent processing the asynchronous task deployment queue.
MainLoopResourceDeploymentMain loop: resource deploymentm_resourceDeploymentProfiler
Resource manager update
Measures the time that the ResourceManager spends processing load and deployment queues.
MainLoopResourceManagerUpdateMain loop: resource manager updatem_resourceManagerUpdateProfiler
Task dispatcher
Measures the time spent executing tasks added to the task scheduler.
MainLoopTaskDispatcherMain loop: task dispatcherm_taskDispatcherProfiler
Task scheduler
Measures the time spent executing periodic tasks added to the task dispatcher, such as animations.
MainLoopTaskSchedulerMain loop: task schedulerm_taskSchedulerProfiler

In the Performance HUD you can show the performance measurement graphs for all main loop task performance profilers. See Showing performance measurement graphs in the Performance HUD.

In the application configuration you can set the sample buffer size in the main loop performance profilers. See MainLoopProfilingSampleBufferCount.

Showing performance measurement graphs in the Performance HUD

You can show performance profiling graphs for the performance profilers which belong to a performance profiling category that is registered in the main loop task profiler registry MainLoopTaskProfilerRegistry. To access the main loop task profiler registry, use Domain::getMainLoopTaskProfilerRegistry.

This section explains how to show performance measurement graphs for the main loop task profilers included in the Profiling build. See Main loop task performance profiling categories.

You can show performance measurement graphs also for the main loop task profilers that you create to measure the performance of your application code. See Measuring the performance of custom main loop tasks.

To show performance measurement graphs in the Performance HUD:

  1. Enable the display of the full Performance HUD:See Configuring your application and PerformanceInfoLevel.
  2. In the application configuration enable showing the performance graphs that you want to see in the Performance HUD. See Main loop task performance profiling categories and ProfilingCategoryFilter.
    For example, to show the Main loop: animation, Main loop: rendering, and Main loop: HUD graphs in the Performance HUD:
  3. (Optional) Set the colors that Kanzi uses to draw the Performance HUD:
    1. In Visual Studio in the file where you want to set the colors, include the performance_info.hpp header file.
      For example, to set the colors that Kanzi uses to draw the Performance HUD of the Scroll view example, in the scroll_view.cpp file add:
      #include <kanzi/core.ui/application/performance_info.hpp>
    2. Set the colors that Kanzi uses to show the Performance HUD graph frames, graph data, and text.
      For example, in the scroll_view.cpp file in the onProjectLoaded function add:
      // Get the performanceInfo object. If the object does not exist, create it.
      PerformanceInfo& performanceInfo = acquirePerformanceInfo();
      // Set the color of graph frames to gray.
      performanceInfo.setBorderColor(ColorRGBA(0.5f, 0.5f, 0.5f));
      // Set the color of graph data to yellow.
      performanceInfo.setLineColor(ColorRGBA(1.0f, 1.0f, 0.0f));
      // Set the color of text to black.
      performanceInfo.setFontColor(ColorRGBA(0.0f, 0.0f, 0.0f));
  4. Build and run your application. See Deploying Kanzi applications.
    To show performance graphs for the predefined main loop task profilers, use the Profiling build.
    For example, on Windows build your application in Visual Studio using the GL_vs2015_Profiling build configuration.

When you run the application, the Performance HUD shows the performance measurement graphs.
If you do not see the graphs, make the application window larger.

Logging Kanzi Engine performance profiling data

To analyze the performance of Kanzi Engine, log the performance profiling data.

Logging startup performance information

You can use the Kanzi startup performance profilers in the Profiling build to measure the time Kanzi Engine spends on different tasks during application startup. See Startup performance profiling categories.

To log startup performance information, build your application using the Profiling build configuration.

For example, to build and run your application on Windows:

  1. In Visual Studio build your application using the GL_vs2015_Profiling build configuration.
  2. Open the command line interface on your computer and run the application so that you direct the application output to a file where you want to store the performance measurements data.
    <MyProject>\Application\bin> ..\output\Win32\GL_vs2015_Profiling\MyApplication.exe > MyApplicationProfiling.log

Kanzi writes the startup performance measurement information to the log.

...
info:profiling> StartupInitialization                        332 018 600 ns
info:profiling> |-- StartupInitializeGraphics                301 798 600 ns
info:profiling> |-- StartupCreateDomain                        1 325 300 ns
info:profiling> |-- StartupInitializeLoadingThreads           27 126 000 ns
info:profiling> |-- StartupRegisterRuntimeAssets                 132 400 ns
info:profiling> |-- StartupLoadPlugins                               200 ns
info:profiling> |-- StartupRegisterMetadata                      449 000 ns
info:profiling> |-- StartupOpenKzb                               398 000 ns
info:profiling> StartupInitializeGL                                  100 ns
info:profiling> StartupResumeGL                                  536 400 ns
info:profiling> StartupLoadPrefab                            388 009 100 ns
info:profiling> StartupInstantiatePrefab                      10 308 400 ns
info:profiling> StartupRegisterDefaultResources                   25 800 ns
info:profiling> StartupAttachPrefab                            8 058 300 ns
info:profiling> StartupResetRenderer                              74 200 ns
info:profiling> StartupOnProjectLoaded                            21 400 ns
info:profiling> Startup profiling data logging took   1 920 000 ns
...

Logging data from a profiler

You can log data from specific profilers:

Logging data from a profiler registry

You can log data from all profilers registered in a specific profiler registry by iterating through the profilers and calling the logAggregateData() or logAllData() function.

For example, to log a summary of performance profiling data from all main loop task profilers when exiting the application:

    // Kanzi calls this function when the application exits.
    virtual void onShutdown() KZ_OVERRIDE
    {
        // Get the main loop task profiler registry MainLoopTaskProfilerRegistry.
        const MainLoopTaskProfilerRegistry& mainRegistry = getDomain()->getMainLoopTaskProfilerRegistry();

        // Go through all profilers in the main loop task profiler registry and log their aggregate data.
        for (MainLoopTaskProfilerRegistry::ProfilerContainer::const_iterator
            profilerIter = mainRegistry.beginProfilers(),
            profilerIterEnd = mainRegistry.endProfilers();
            profilerIter != profilerIterEnd; ++profilerIter)
        {
            (*profilerIter)->logAggregateData();
        }
    }

See also

Measuring application performance

Measuring the performance of your application code

Configuring your application